<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
	  "http://www.w3.org/TR/html4/loose.dtd">
<html>
  <head>
    <title>The deal.II Readme on interfacing to Ginkgo</title>
    <link href="../screen.css" rel="StyleSheet">
    <meta name="copyright" content="Copyright (C) 2008 - 2019 by the deal.II authors">
    <meta name="keywords" content="deal.II">
  </head>

  <body>

    <h1>Interfacing <acronym>deal.II</acronym> to Ginkgo</h1>

    <p>
        <a href="https://github.com/ginkgo-project/ginkgo"
           target="_top">Ginkgo</a> is
        A numerical linear algebra software package that provides its users with
        highly optimized fine grid level linear algebra operations. It currently has
        the capability to solve on the CPU with the support of OpenMP and on the GPU
        with NVIDIA's CUDA libraries. For some operations it uses NVIDIA's own libraries, CuSparse
        and CuBLAS, but some routines also have self implemented CUDA functions.See the <a href="https://ginkgo-project.github.io/ginkgo/doc/develop/index.html" target="_top"> Ginkgo documentation </a>
        for more details.
    </p>

    <p>
      <acronym>deal.II</acronym> has wrapper classes to the linear algebra
      parts of Ginkgo that provide almost the
      same interfaces as the built-in <acronym>deal.II</acronym> linear algebra operations.
    </p>

    <h2>Installing <acronym>deal.II</acronym> with Ginkgo</h2>

    <p>
        During the CMake configuration, the following flags should be specified:
        <ul>
            <li> <code>-DDEAL_II_WITH_GINKGO=ON</code>, to enable the Ginkgo library.
            <li> <code>-DGINKGO_DIR=<path_to_ginko></code>, to specify the path where Ginkgo has been installed.
        </ul>
    </p>

    <h3>Installing Ginkgo</h3>

    <p>
        Installing Ginkgo is quite simple. Ginkgo currently uses CMake and hence one can use
        the following commands to easily install Ginkgo. For different dependencies and compatible
        libraries, please refer to <a href="https://github.com/ginkgo-project/ginkgo"
                                      target="_top">Ginkgo</a>.
        The different flags that can be added are:
        <ul>
           <li> <code> -DGINKGO_BUILD_REFERENCE={ON,OFF}</code>: Builds the reference single thread implementation
        used to check the more sophisticated implementations of the GPU/CPU.
           <li> <code> -DGINKGO_BUILD_CUDA={ON,OFF}</code>: Builds the GPU implementation, specifically the NVIDIA
        CUDA implementations. This needs CUDA to be installed on the machine.
           <li> <code> -DGINKGO_BUILD_OMP={ON,OFF}</code>: Builds the multithreaded OpenMP implementations.
        </ul>
        To install Ginkgo, you would need to:
      <pre>
	git clone https://github.com/ginkgo-project/ginkgo.git
  mkdir build; cd build
  cmake -DGINKGO_BUILD_REFERENCE=on/off -DGINKGO_BUILD_CUDA=on/off -DGINKGO_BUILD_OMP=on/off -DCMAKE_INSTALL_PREFIX=/path/to/install/ -DCMAKE_BUILD_TYPE=Release/Debug
	make install
      </pre>
    </p>

    <h4>Running the Ginkgo tests</h4>

    <p>
        Ginkgo uses <code>gtests</code> to run unit tests. The reference implementations are
        non-optimized versions to which the OpenMP and CUDA versions are compared with for
        correctness.

        The following command, executed in Ginkgo's build directory, launches its test suite.
      <pre>
	make test
      </pre>
      The output should contain several lines of the form:
      <pre>
     Start  1: path/to/test
 1/13 Test  #1: path/to/test .............................   Passed    0.01 sec
      </pre>
      To run only a specific test for more details, from the build directory, run
      <pre>
	./path/to/test
      </pre>
    </p>

    <hr />
    <div class="right">
      <a href="http://validator.w3.org/check?uri=referer" target="_top">
        <img style="border:0" src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a>
      <a href="http://jigsaw.w3.org/css-validator/check/referer" target="_top">
        <img style="border:0;width:88px;height:31px" src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
    </div>
  </body>
</html>
